
/*
 * Copyright (C) 2008-2009 Archie L. Cobbs. All rights reserved.
 *
 * $Id: SidekarMap.java 288 2010-01-11 19:45:47Z archie.cobbs $
 */

package org.dellroad.sidekar.annotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Tags a method as the access method for an entity map field.
 *
 * <p>
 * This annotation should annotate the "getter" method in the field's containing entity type.
 * There should be no "setter" method; Sidekar map fields are never null (and default to empty).
 *
 * <p>
 * The annotated method must satisfy these constraints:
 * <ul>
 * <li>It must take zero parameters</li>
 * <li>It's return type must be {@link java.util.Map Map&lt;K, V&gt;} where {@code K} is the map's key type and
 *  {@code V} is the map's value type</li>
 * <li>The key and value types {@code <K, V>} must be supported "nestable" field types
 * </ul>
 *
 * <p>
 * The map's key and value types are inferred from the generic type parameters {@code K} and {@code V}
 * of the method's return type.
 *
 * <p>
 * If the key or value type is a Java primitive wrapper type, then {@code null} values of that type are not supported.
 *
 * @see org.dellroad.sidekar.FieldType Supported field types
 */
@Documented
@Inherited
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface SidekarMap {

    /**
     * Specifies the name of this map field.
     *
     * <p>
     * If "" (the default), the field name is taken from the method name using the
     * normal Java bean property naming rules, in which case the method name must
     * have the form of a getter method (e.g., {@code getFoo}).
     */
    String value() default "";
}

